How to Document Wisely

There’s nothing quite as effective as putting an accurate estimate of the amount of time it will take to produce good documentation into an estimate to slacken the demand for documentation. The truth is cold and hard: documentation, like testing, can take many times longer than developing code.

When it comes to actually documenting code itself, as opposed to producing documents that can actually be read by non-programmers, the best programmers I’ve ever known hold a universal sentiment: write self-explanatory code and only document code in the places that you cannot make it clear by writing the code itself. There are two good reasons for this. First, anyone who needs to see code-level documentation will in most cases be able to and prefer to read the code anyway. Admittedly, this seems easier to the experienced programmer than to the beginner. More importantly however, is that the code and the documentation cannot be inconsistent if there is no documentation. The source code can at worst be wrong and confusing. The documentation, if not written perfectly, can lie, and that is a thousand times worse.

• Writing code knowing that someone will have to read it;
• Choosing a solution that is straightforward, even if you could get by with another solution faster;
• Thinking about the reader and spending some of your precious time to make it easier on her; and

Next How to Work with Poor Code